COMPILE_OPT

The COMPILE_OPT statement allows you to give the IDL compiler information that changes some of the default rules for compiling the function or procedure within which the COMPILE_OPT statement appears.

In all new code we recommend the use of:

COMPILE_OPT IDL3

We further recommend the use of:

COMPILE_OPT IDL3, HIDDEN

in routines that are not intended to be called directly by users (for example, helper routines that are part of a larger package).

Syntax

COMPILE_OPT opt₁ [, opt₂, ..., opt_n]

Arguments

opt_n

This argument can be any of the following:

• IDL2: A shorthand way of saying:

COMPILE_OPT DEFINT32, STRICTARR

• IDL3: A shorthand way of saying:

COMPILE_OPT DEFINT32, FLOAT64, LOGICAL_PREDICATE, STRICTARR

• DEFINT32: If set, then integer constants in the range -32767 to 32767 will default to the 32-bit LONG type rather than the usual 16-bit INT type. This takes effect from the point where the COMPILE_OPT statement appears in the routine and remains in effect until the end of the routine. Integer constants with the "s" or "us" type specifier will remain as type INT or UINT. The following table illustrates how the DEFINT32 argument changes the interpretation of integer constants.

  Constant	Normal Type	DEFINT32 Type
  42	INT	LONG
  0x42	INT	LONG
  42u	UINT	ULONG
  0x42u	UINT	ULONG
  42s	INT	INT
  42us	UINT	UINT

• FLOAT64: If set, then floating-point constants will default to the 64-bit DOUBLE type rather than the usual 32-bit FLOAT type. This takes effect from the point where the COMPILE_OPT statement appears in the routine and remains in effect until the end of the routine. Floating-point constants with an "e" exponent will remain as type FLOAT, while constants with a "d" will remain as type DOUBLE. The following table illustrates how the FLOAT64 argument changes the interpretation of floating-point constants.

  Constant	Normal Type	FLOAT64 Type
  2459810.8580208337	FLOAT (2459810.8)	DOUBLE (2459810.8580208337)
  3.14e	FLOAT	FLOAT
  1.23e20	FLOAT	FLOAT
  3.14d	DOUBLE	DOUBLE

• HIDDEN: This routine should not be displayed by HELP, unless the FULL keyword to HELP is used. This directive can be used to hide helper routines that regular IDL users are not interested in seeing.

A side-effect of making a routine hidden is that IDL will not print a “Compile module” message for it when it is compiled from the library to satisfy a call to it. This makes hidden routines appear built-in to the user.

• LOGICAL_PREDICATE: When running this routine, from the point where the COMPILE_OPT statement appears until the end of the routine, treat any non-zero or non-NULL predicate value as “true,” and any zero or NULL predicate value as “false.”

A predicate expression is an expression that is evaluated as being “true” or “false” as part of a statement that controls program execution. IDL evaluates such expressions in the following contexts:

– IF...THEN...ELSE statements

– ? : inline conditional expressions

– WHILE...DO statements

– REPEAT...UNTIL statements

– The result from an object's INIT method to determine if the object was successfully created

By default, IDL uses the following rules to determine whether an expression is true or false:

– Integer: An integer is considered true if its least significant bit is 1, and false otherwise. Hence, odd integers are true and even integers (including zero) are false. This interpretation of integer truth values is sometimes referred to as “bitwise,” reflecting the fact that the value of the least significant bit determines the result.

– Other: Non-integer numeric types are true if they are non-zero, and false otherwise. String and heap variables (pointers and object references) are true if they are non-NULL, and false otherwise.

When LOGICAL_PREDICATE is set, IDL uses the following rules to determine whether an expression is true or false:

– All Types: A number is considered true if its value is non-zero, and false otherwise. String and heap variables (pointers and object references) are true if they are non-NULL, and false otherwise.

Note: IDL's NOT operator is a bitwise operator (1’s complement), and is generally unsuitable for predicate expressions. For example:

WHILE (NOT EOF(lun)) DO ...

The EOF function returns 1 when it reaches the end of file. However, the expression "NOT 1" has the numeric value –2. When LOGICAL_PREDICATE is not in use, the WHILE statement sees –2 as false and the loop will terminate; if LOGICAL_PREDICATE is in use, –2 is a true value and the above loop will never terminate. Instead, you should use the ~ logical negation operator:

WHILE (~EOF(lun)) DO ...

This version will work properly regardless of the LOGICAL_PREDICATE setting.

• NOSAVE: If this directive is set, then by default the routine will not be saved into IDL code save files. You can override this behavior by specifying the routine name as one of the input arguments to SAVE. In that case the NOSAVE compile option will be ignored.
• OBSOLETE: If the user has !WARN.OBS_ROUTINES set to True, attempts to compile a call to this routine will generate warning messages that this routine is obsolete. This directive can be used to warn people that there may be better ways to perform the desired task.
• STATIC: The STATIC compile option indicates that the user is allowed to call this method as a static class method. This compile option is only useful for methods and is ignored for regular functions and procedures. Note that methods marked as STATIC can also be called on an object instance as a "normal" instance method. However, if you attempt to make a static call to a method that is not marked as STATIC, you will receive a runtime error. See Creating Static Methods and Static Methods for details.
• STRICTARR: While compiling this routine, IDL will only allow square brackets to be used to index arrays, and will not allow parentheses. If IDL encounters parentheses, it will assume that this is being used for a function call. Use of STRICTARR can eliminate most uses of the FORWARD_FUNCTION definition.

Note: STRICTARR has no effect on the use of parentheses to reference structure tags using the tag index, since this is not an array indexing operation. For example, no syntax error will occur when compiling the following code:

COMPILE_OPT STRICTARR

mystruct = {a:0, b:1}

print, mystruct.(0)

• STRICTARRSUBS: When IDL subscripts one array using another array as the source of array indices, the default behavior is to clip any out-of-range indices into range and then quietly use the resulting data without error. This behavior is described in Understanding Array Subscripts. Specifying STRICTARRSUBS will instead cause IDL to treat such out-of-range array subscripts within the body of the routine containing the COMPILE_OPT statement as an error. The position of the STRICTARRSUBS option within the module is not important: All subscripting operations within the entire body of the specified routine will be treated this way.

Version History

5.3	Introduced
5.6	Added STRICTARRSUBS option
6.0	Added LOGICAL_PREDICATE option
8.3	Added STATIC option
8.4	Added NOSAVE option
8.9	Added FLOAT64 and IDL3 options